Crate num_bigint

Big Integer Types for Rust

• A BigUint is unsigned and represented as a vector of digits.
• A BigInt is signed and is a combination of BigUint and Sign.

Common numerical operations are overloaded, so we can treat them the same way we treat other numbers.

Example

use num_bigint::BigUint;
use num_traits::One;

// Calculate large fibonacci numbers.
fn fib(n: usize) -> BigUint {
    let mut f0 = BigUint::ZERO;
    let mut f1 = BigUint::one();
    for _ in 0..n {
        let f2 = f0 + &f1;
        f0 = f1;
        f1 = f2;
    }
    f0
}

// This is a very large number.
println!("fib(1000) = {}", fib(1000));

It’s easy to generate large random numbers:

use num_bigint::{ToBigInt, RandBigInt};

let mut rng = rand::thread_rng();
let a = rng.gen_bigint(1000);

let low = -10000.to_bigint().unwrap();
let high = 10000.to_bigint().unwrap();
let b = rng.gen_bigint_range(&low, &high);

// Probably an even larger number.
println!("{}", a * b);

See the “Features” section for instructions for enabling random number generation.

Features

The std crate feature is enabled by default, which enables std::error::Error implementations and some internal use of floating point approximations. This can be disabled by depending on num-bigint with default-features = false. Either way, the alloc crate is always required for heap allocation of the BigInt/BigUint digits.

Random Generation

num-bigint supports the generation of random big integers when the rand feature is enabled. To enable it include rand as

rand = "0.8"
num-bigint = { version = "0.4", features = ["rand"] }

Note that you must use the version of rand that num-bigint is compatible with: 0.8.

Arbitrary Big Integers

num-bigint supports arbitrary and quickcheck features to implement arbitrary::Arbitrary and quickcheck::Arbitrary, respectively, for both BigInt and BigUint. These are useful for fuzzing and other forms of randomized testing.

Serialization

The serde feature adds implementations of Serialize and Deserialize for both BigInt and BigUint. Their serialized data is generated portably, regardless of platform differences like the internal digit size.

Compatibility

The num-bigint crate is tested for rustc 1.60 and greater.

Structs

• BigInt
  A big signed integer type.
• BigUint
  A big unsigned integer type.
• ParseBigIntError
• RandomBitsrand
  A random distribution for BigUint and BigInt values of a particular bit size.
• TryFromBigIntError
  The error type returned when a checked conversion regarding big integer fails.
• U32Digits
  An iterator of u32 digits representation of a BigUint or BigInt, ordered least significant digit first.
• U64Digits
  An iterator of u64 digits representation of a BigUint or BigInt, ordered least significant digit first.
• UniformBigIntrand
  The back-end implementing rand’s UniformSampler for BigInt.
• UniformBigUintrand
  The back-end implementing rand’s UniformSampler for BigUint.

Enums

• Sign
  A Sign is a BigInt’s composing element.

Traits

• RandBigIntrand
  A trait for sampling random big integers.
• ToBigInt
  A generic trait for converting a value to a BigInt. This may return None when converting from f32 or f64, and will always succeed when converting from any integer or unsigned primitive, or BigUint.
• ToBigUint
  A generic trait for converting a value to a BigUint.